---
title: Astro 사이트를 GitLab Pages에 배포하세요
description: GitLab Pages를 사용하여 Astro 사이트를 웹에 배포하는 방법.
sidebar:
  label: GitLab Pages
type: deploy
logo: gitlab
supports: ['static'] 
i18nReady: true
---
import { Steps } from '@astrojs/starlight/components';

[GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/)를 사용하여 [GitLab](https://about.gitlab.com/) 프로젝트, 그룹 또는 사용자 계정을 위한 Astro 사이트를 호스팅할 수 있습니다.

:::tip[예시를 찾고 계시나요?]
[공식 GitLab Pages Astro 예시 프로젝트](https://gitlab.com/pages/astro)를 확인해 보세요!
:::

## 배포 방법

사이트를 자동으로 빌드하고 배포하는 GitLab CI/CD를 사용하여 Astro 사이트를 GitLab Pages에 배포할 수 있습니다. 이렇게 하려면 소스 코드가 GitLab에서 호스팅되어야 하며 Astro 프로젝트에 다음과 같은 변경을 수행해야 합니다.

<Steps>

1. `astro.config.mjs`의 [`site`](/ko/reference/configuration-reference/#site)와 [`base`](/ko/reference/configuration-reference/#base) 옵션을 설정합니다.

    ```js title="astro.config.mjs" ins={4-5}
    import { defineConfig } from 'astro/config';

    export default defineConfig({
      site: 'https://<username>.gitlab.io',
      base: '/<my-repo>',
      outDir: 'public',
      publicDir: 'static',
    });
    ```

    `site`

    `site`의 값은 다음 중 하나여야 합니다.

    - 사용자 이름을 기반으로 하는 URL: `https://<username>.gitlab.io`
    - 그룹 이름을 기반으로 하는 URL: `https://<groupname>.gitlab.io`
    - Gitlab 프로젝트 설정에서 구성한 경우, 사용자 지정 도메인: `https://example.com`

    Gitlab의 자체 관리 인스턴스의 경우, `gitlab.io`를 인스턴스의 Pages 도메인으로 바꿉니다.

    `base`

    Astro가 저장소의 이름 (예: `/my-repo`)을 웹사이트의 루트로 취급하도록 `base` 값을 입력해야 할 수 있습니다.  

    :::note
      페이지가 루트 폴더에서 제공되는 경우 `base` 매개변수를 설정하지 마세요.
    :::

    `base`의 값은 슬래시로 시작하는 저장소의 이름이어야 합니다 (예: `/my-blog`). 이는 Astro가 웹사이트의 루트가 기본 `/`가 아닌 `/my-repo`라는 것을 이해하도록 하기 위함입니다.

    :::caution
        이 값이 구성되면 모든 내부 페이지 링크 앞에 `base` 값을 붙여야 합니다.

      ```astro ins="/my-repo"
      <a href="/my-repo/about">About</a>
      ```

    [`base` 값 구성](/ko/reference/configuration-reference/#base)에 대해 더 자세히 알아보세요.
    :::


2. `public/` 디렉터리의 이름을 `static/`으로 변경합니다.

3. `astro.config.mjs`에서 `outDir: 'public'`을 설정합니다. 이 설정은 Astro가 정적 빌드 출력을 `public`이라는 폴더에 저장하도록 지시하며, 이 폴더는 노출된 파일에 접근하기 위해 GitLab Pages가 요구하는 폴더입니다.

   Astro 프로젝트에서 정적 파일의 소스로 [`public/` 디렉터리](/ko/basics/project-structure/#public)를 사용하고 있었다면 이름을 바꾸고 `publicDir` 값으로 `astro.config.mjs`의 새 폴더 이름을 사용합니다.

   예를 들어 `public/` 디렉터리의 이름이 `static/`으로 변경된 경우 올바른 `astro.config.mjs` 설정은 다음과 같습니다.

   ```js title="astro.config.mjs" ins={4-5}
   import { defineConfig } from 'astro/config';
   
   export default defineConfig({
     site: 'https://<user>.gitlab.io',
     base: '/<project-name>',
     outDir: 'public',
     publicDir: 'static',
   });
   ```

4. `.gitignore`에서 빌드 출력을 변경합니다. 이 예시에서는 `dist/`를 `public/`으로 변경해야 합니다.

    ```diff  title=".gitignore"
    # 빌드 출력
    -dist/
    +public/
    ```

5. 프로젝트 루트에 아래 내용으로 `.gitlab-ci.yml`이라는 파일을 생성합니다. 이렇게 하면 콘텐츠를 변경할 때마다 사이트를 빌드하고 배포할 수 있습니다.

   ```yaml title=".gitlab-ci.yml"
   pages:
     # 앱을 빌드하는 데 사용될 Docker 이미지
     image: node:lts

     before_script:
       - npm ci

     script:
       # 여기에서 앱 빌드와 관련된 단계를 지정하세요.
       - npm run build

     artifacts:
       paths:
         # 게시하기 위해 빌드된 파일이 포함된 폴더입니다.
         # 이것을 "public"라고 불러야 합니다.
         - public

     only:
       # 아래 브랜치에 푸시가 있는 경우에만 새 빌드를 트리거하고 배포합니다.
       - main
   ```

6. 변경 사항을 커밋하고, GitLab에 푸시합니다.

7. Gitlab에서 저장소의 **Deploy** 메뉴로 이동하여 **Pages**를 선택합니다. 여기에 GitLab Pages 웹사이트의 전체 URL이 표시됩니다. `https://username.gitlab.io/my-repo` URL 형식을 사용하려면 이 페이지에서 **Use unique domain** 설정을 선택 해제하세요.

</Steps>

이제 사이트가 게시되었습니다! Astro 프로젝트 저장소에 변경 사항을 푸시하면 GitLab CI/CD 파이프라인이 자동으로 배포합니다.
